#####################################################################
# Product:      KnowledgeEngine (Plone Edition)
#
# File:         AssessmentAttribute.py
#
# Copyright:    Copyright (c) 2005, Faulkner Technologies
#
# Author:       Brian Oliver
#
# Description:  Instances of the AssessmentAttribute class
#               store/represent the DYNAMIC state of an assessment.
#           
#               This class is different from the AssessmentComponentState
#               which is designed to store actual assessment state.
#
#               This class provides the ability to dynamically 'attach'
#               additional persistent state to an assessment that 
#               is not core to an actual assessment.  Classic uses
#               of assessment attributes are to store/cache calculated
#               values like scores and other time-consuming possibly
#               derived assessment attributes.
#
#               NOTE: it should be possible to remove all of 
#               the attributes of an assessment without effecting
#               the ability for the assessment to be used semantically.
#
#               NOTE: AssessmentAttributes are identified using
#               AssessmentAttributeHandles that embody both the 
#               unique identifier, attribute value type and model
#               for which the attribute applies.
#
#               Collections of AssessmentAttributes are managed
#               by instances of the Assessment class!  They are typically
#               lazily loaded.
#
# See Also:     AssessmentAttributeHandle, Assessment, 
#               AssessmentComponentValueTypes and AssessmentStorageService
#####################################################################

#####################################################################
## KnowledgeEngine Library Imports
from Common import *
from AssessmentAttributeHandle import AssessmentAttributeHandle

#####################################################################
## Zope Library Imports
from Globals import InitializeClass
from AccessControl import ClassSecurityInfo
from AccessControl.Role import RoleManager
from DateTime import DateTime
 
#####################################################################
## Python Library Imports
# (None)

#####################################################################
## AssessmentAttribute Class Definition
class AssessmentAttribute(RoleManager):
    """
        An in-memory storage-agnostic representation of derived
        state for an assessment.
    """
        
    #---------------------------------------------------------------#

    #declare security so ClassInfo may be accessed in DTML/ZPT etc
    security = ClassSecurityInfo()
    security.declareObjectPublic()
    security.setDefaultAccess("allow")

    #---------------------------------------------------------------#

    def __init__(self, attributeHandle, assessmentIdentity, value):
        """
            New AssessmentAttribute is constructed using using four properties;
            * The identity of the assessment (String)
            * The attributeHandle to identify attribute
            * The value (Polymorhic)
        """
               
        ### the following attributes are generally stored together (and need to be persisted)
        self.attributeHandle = attributeHandle
        self.assessmentIdentity = assessmentIdentity
        self.instantCreated = DateTime()
        self.instantModified = DateTime()
        self.isNew = true
        self.isModified = true
        self.value = value

    #---------------------------------------------------------------#

    def getAttributeHandle(self):
        """
            Returns the handle that uniquely identifies the type of
            the attribute
            
            RETURN TYPE: AssessmentAttributeHandle
        """
        
        return self.attributeHandle

    #---------------------------------------------------------------#

    def getAssessmentIdentity(self):
        """
            Returns the unique identity for the assessment that owns the attribute
            
            RETURN TYPE: String
        """
        
        return self.assessmentIdentity

    #---------------------------------------------------------------#

    def getInstantCreated(self):
        """
            Returns the instant in time (as a DateTime) that the attribute was created
            
            RETURN TYPE: DateTime
        """

        return self.instantCreated

    #---------------------------------------------------------------#

    def setInstantCreated(self, instantCreated):
        """
            Sets the instant in time (as a DateTime) that the attribute was created
        """

        self.instantCreated = instantCreated

    #---------------------------------------------------------------#

    def getInstantModified(self):
        """
            Returns the instant in time (as a DateTime) that the attribute was modified
            
            RETURN TYPE: DateTime
        """

        return self.instantModified

    #---------------------------------------------------------------#

    def setInstantModified(self, instantModified):
        """
            Sets the instant in time (as a DateTime) that the attribute was modified
        """

        self.instantModified = instantModified

    #---------------------------------------------------------------#

    def getIsNew(self):
        """
            Returns if the attribute is new (not yet persisted)
            
            RETURN TYPE: Boolean
        """

        return self.isNew

    #---------------------------------------------------------------#

    def setIsNew(self, isNew):
        """
            Sets if the attribute is new (not yet persisted)
        """

        self.isNew = isNew

    #---------------------------------------------------------------#

    def getIsModified(self):
        """
            Returns if the attribute has been modified since created or loaded 
            
            RETURN TYPE: Boolean
        """

        return self.isModified

    #---------------------------------------------------------------#

    def setIsModified(self, isModified):
        """
            Sets if the attribute has been modified since created or loaded 
        """

        self.isModified = isModified

    #---------------------------------------------------------------#

    def getValue(self):
        """
            Returns the value of the attribute
            RETURN TYPE: Polymorphic
        """

        return self.value

    #---------------------------------------------------------------#

    def setValue(self, value):
        """
            Sets the value of the attribute
        """

        self.value = value
        self.isModified = true

    #---------------------------------------------------------------#
                
#####################################################################
## Class Initialisation
InitializeClass(AssessmentAttribute)
